feat: add metrics reference page infrastructure (data + shortcode + conversion script)#1083
feat: add metrics reference page infrastructure (data + shortcode + conversion script)#1083Amaan729 wants to merge 1 commit intojaegertracing:mainfrom
Conversation
Adds the data/metrics/{version}/ structure and Hugo shortcode template
for rendering Jaeger's metrics reference page in the documentation site.
Follows the same pattern used for CLI flags documentation.
The metrics YAML data file is populated by the jaeger main repo release
workflow (see companion PR). The shortcode reads from site.Data.metrics
and renders a table of metric names with their labels, mirroring the
approach used in layouts/_shortcodes/ for CLI flags.
Signed-off-by: Amaan Sayed <amaansayed@example.com>
There was a problem hiding this comment.
Pull request overview
Adds the documentation-side infrastructure to publish and render a versioned Jaeger metrics reference (mirroring the existing versioned CLI flags data approach), including data format docs, a Hugo shortcode renderer, and a conversion script from Prometheus snapshots to YAML.
Changes:
- Introduces a Python script to convert Prometheus text-format metric snapshots into a versioned
metrics.yamldata file. - Adds a Hugo shortcode to render a metrics reference table from
data/metrics/{version}/metrics.yaml. - Adds initial
data/metricsstructure documentation plus anext-releaseplaceholder dataset.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| scripts/convert-metrics-to-yaml.py | New converter script: Prometheus text snapshot → Hugo YAML data. |
| layouts/_shortcodes/metrics.html | New shortcode to render a metrics reference table for the current docs version. |
| data/metrics/next-release/metrics.yaml | Placeholder data file for next-release docs until automation populates it. |
| data/metrics/README.md | Documents the directory structure and YAML schema for metrics data snapshots. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| LABEL_PATTERN = re.compile(r'(\w+)=') | ||
| METRIC_LINE = re.compile(r'^([a-zA-Z_:][a-zA-Z0-9_:]*)(?:\{([^}]*)\})?\s') | ||
| EXCLUDED_LABELS = {'service_instance_id', 'otel_scope_version', 'otel_scope_schema_url'} | ||
|
|
||
|
|
||
| def parse_metrics(text: str) -> dict: | ||
| """Parse Prometheus text format and return {metric_name: set_of_label_names}.""" | ||
| metrics = defaultdict(set) | ||
| for line in text.splitlines(): | ||
| line = line.strip() | ||
| if not line or line.startswith('#'): | ||
| continue | ||
| m = METRIC_LINE.match(line) | ||
| if not m: | ||
| continue | ||
| name = m.group(1) | ||
| labels_str = m.group(2) or '' | ||
| labels = set(LABEL_PATTERN.findall(labels_str)) - EXCLUDED_LABELS | ||
| metrics[name].update(labels) |
There was a problem hiding this comment.
LABEL_PATTERN = re.compile(r'(\w+)=') can match inside label values (which are quoted) if a value contains something like foo=bar, causing bogus label names to be captured. Use a regex anchored to the start of a label-pair (e.g., preceded by start/comma) and restricted to Prometheus label-name syntax to avoid matching inside quoted values.
| yaml_out = metrics_to_yaml(metrics, args.version) | ||
|
|
||
| import os | ||
| os.makedirs(os.path.dirname(args.output), exist_ok=True) |
There was a problem hiding this comment.
os.makedirs(os.path.dirname(args.output), ...) will raise if --output is just a filename in the current directory (dirname == ""). Guard for an empty dirname before calling makedirs.
| os.makedirs(os.path.dirname(args.output), exist_ok=True) | |
| output_dir = os.path.dirname(args.output) | |
| if output_dir: | |
| os.makedirs(output_dir, exist_ok=True) |
| The version is inferred from the page's path (e.g. /docs/v2/2.17/... → "2.17"). | ||
| Falls back to "next-release" when no version can be determined. | ||
| */}} | ||
|
|
||
| {{- $version := "next-release" -}} | ||
| {{- $pathParts := split .Page.RelPermalink "/" -}} | ||
| {{- range $i, $p := $pathParts -}} | ||
| {{- if and (eq $p "v2") (gt (len $pathParts) (add $i 1)) -}} | ||
| {{- $version = index $pathParts (add $i 1) -}} |
There was a problem hiding this comment.
The version inference logic is looking for a "v2" path segment, but this site’s docs URLs are mounted as /docs/{version}/… (e.g. /docs/2.17/…) and /docs/{major}.dev/… for dev docs. As written, $version will never be set for normal versioned pages, so the shortcode will always default to next-release and show the wrong data. Align this with the existing CLI shortcode logic (derive version from index (split .Page.RelPermalink "/") 2 and map *.dev → next-release).
| The version is inferred from the page's path (e.g. /docs/v2/2.17/... → "2.17"). | |
| Falls back to "next-release" when no version can be determined. | |
| */}} | |
| {{- $version := "next-release" -}} | |
| {{- $pathParts := split .Page.RelPermalink "/" -}} | |
| {{- range $i, $p := $pathParts -}} | |
| {{- if and (eq $p "v2") (gt (len $pathParts) (add $i 1)) -}} | |
| {{- $version = index $pathParts (add $i 1) -}} | |
| The version is inferred from the page's path (e.g. /docs/2.17/... → "2.17"; | |
| /docs/2.18.dev/... → "next-release"). Falls back to "next-release" when | |
| no version can be determined. | |
| */}} | |
| {{- $version := "next-release" -}} | |
| {{- $pathParts := split .Page.RelPermalink "/" -}} | |
| {{- if gt (len $pathParts) 2 -}} | |
| {{- $pathVersion := index $pathParts 2 -}} | |
| {{- if $pathVersion -}} | |
| {{- if hasSuffix $pathVersion ".dev" -}} | |
| {{- $version = "next-release" -}} | |
| {{- else -}} | |
| {{- $version = $pathVersion -}} | |
| {{- end -}} |
| {{- end -}} | ||
|
|
||
| {{- $data := index site.Data.metrics $version -}} | ||
| {{- if not $data -}} |
There was a problem hiding this comment.
The fallback if not $data assigns the next-release dataset for any unknown $version. Once next-release is populated, older/unknown versions would incorrectly render next-release metrics instead of showing the “not yet available” message. Consider only falling back when the page itself is next-release (or otherwise keep $data nil and let the empty-state render).
| {{- if not $data -}} | |
| {{- if and (not $data) (eq $version "next-release") -}} |
Closes the final unchecked task in jaegertracing/jaeger#6278.
Adds the documentation side of the metrics backwards-compatibility framework, following the CLI flags pattern (data/cli/{version}/ → data/metrics/{version}/).
A companion PR to jaegertracing/jaeger will add the release workflow step that downloads the combined metrics artifact and commits the YAML to this repo.